home *** CD-ROM | disk | FTP | other *** search
/ BBS in a Box 12 / BBS in a box XII-1.iso / Files / Util / B / Bro.sit / Bro.Doc next >
Encoding:
Text File  |  1988-07-02  |  8.2 KB  |  215 lines  |  [TEXT/MACA]
  1. 150 ASCII retrieve of <INFO-MAC>BROADCAST-05B3-DOC.TXT.1 started.
  2. BroadCast 0.5b3
  3. ===============
  4.  
  5. Copyright 1988 Joachim Lindenberg, University of Karlsruhe,
  6. Federal Republic of Germany. All rights reserved.
  7.  
  8. BroadCast is a copyrighted procuct. Permission is granted to
  9. everybody not envolved in military projects to use it freely
  10. at no charge, as long as it is not repackaged or sold.
  11.  
  12. BroadCast may not be used within other products without
  13. prior express permission in writing by University of Karlsruhe.
  14. Our licensing terms require you to grant a site license of your
  15. product at no charge to 
  16.  
  17.     University of Karlsruhe,
  18.     Joachim Lindenberg, Fakultaet fuer Informatik
  19.     Postfach 6980, 7500 Karlsruhe 1
  20.     Federal Republic of Germany
  21.  
  22. [ Include standard disclaimers - you know that it may habe bugs.
  23.   Mail bug reports and/or other stuff to joachim@ira.uka.de. ]
  24.  
  25.  
  26.  
  27.  
  28. MenuIcons
  29. =========
  30.  
  31. BroadCast supports sending/receiving of any icon. Note that the icon
  32. is actually transmitted via the network. There is no need for the
  33. receiver to know the icons in advance.
  34.  
  35. The 6 icons currently included are BroadCast itself and the icons  
  36. LaserWriter, AppleShare, Disk, Phone and Bomb which are stolen from
  37. Apple files.
  38.  
  39. You may change BroadCast to include more/other icons as well. The
  40. following defines the structure of the MenuRecord used by the
  41. icon menu defintion function, which may be translated to a equivalent
  42. resource definition easily:
  43.  
  44. type     IconMenuInfo = RECORD
  45.          menuId: INTEGER;
  46.          menuWidth: INTEGER;
  47.          menuHeight: INTEGER;
  48.          menuProc: Handle;
  49.          enableFlags: LONGINT;
  50.          filler : integer; {Jmakes ResEdit happy }
  51.          height, width : integer;
  52.          icon : array [0..99] of integer; { resource ids of icons } 
  53.     END;
  54.  
  55. Warning: Don't open the MENU resource without holding down the option
  56. key. ResEdit doesn't know the structure given above. Instead it assumes
  57. a standard text menu definition. The filler is only good to stop ResEdit
  58. from displaying garbage.
  59.  
  60. All icons should be numbered in the range -4096 through -4065. The icon
  61. with id -4096 is the default icon used by the receiver.
  62.  
  63. Note that the icon is optional to a message. The CAP version of BroadCast
  64. does not support (at least at the time being) receiving of icons.
  65.  
  66.  
  67.  
  68. Specification of BroadCast 0.5b3
  69. ================================
  70.  
  71. The following notes describe the interface and some aspects of the
  72. implementation of BroadCast 0.5b3.
  73.  
  74.  
  75. Namebinding
  76. ===========
  77.  
  78. Any node with Broadcast enabled registers itself as ChooserName:BroadCast:*
  79. - or whatever typestring is defined in STR -4096. If disabled, the type
  80. string of STR -4096 will be prefixed by the string Prefix (declaration.i)
  81. which consists of a -, thus the name will not be visible to the lookup of
  82. BroadCast (I tested differentiating through use of uppercase/lowercase
  83. characters, but NBP lookup turned out not to be casesensitive). Any program
  84. (e.g. mailserver) may choose to send broadcasts to both enabled and disabled
  85. BroadCast clients, depending upon its needs. The disabling feature just
  86. stops other BroadCast clients from sending. (BroadCast verifies that STR -4096
  87. does not start with the Prefix character, thus the simplest approach to
  88. send messages to disabled clients is impossible)
  89.  
  90.  
  91. Sending Messages
  92. ================
  93.  
  94. After looking up an entity by name, an ATPSendRequest is used to send the
  95. actual message. 
  96.  
  97. The message that is sent by the ATPSendRequest must contain the following data
  98. - userData set to zero. other values might indicate future expansions.
  99. - requestPtr pointing to the following record
  100.     record
  101.       messagetext : str255;  { required }
  102.       messageicon : Icon;    { optionally }
  103.     end;
  104.   - The name of the sender (choosername) is delimited by Delimiter 
  105.     (option-dash, ascii 0xD1) The receiver searches for the last occurence
  106.     of this character in the message text.
  107.   - The string may be transmitted either by declared size (256 bytes) or by
  108.     actual size (length + 1 bytes). The message may be :
  109.       256 - if just the message text is transmitted using the declared size
  110.       length + 1 - if the message text is transmitted using the actual size
  111.       384 - if message + icon are transmitted using declared sizes
  112.       length + 129 - if message text and icon are transmitted packed.
  113.       
  114.       
  115. Message Response
  116. ================
  117.  
  118. The receiver will return the message by an ATPResponse. The response message
  119. is the time (local to the receiver) the message was received on. Userbytes
  120. are returned zeroed.
  121.  
  122. There is no user feedback upon success/fail of a message sent. This might
  123. be changed in a future version. BroadCast does sort of 'best effort delivery'.
  124. The message will be saved until a new one arrives, no queuing is done.
  125.  
  126.  
  127. Action
  128. ======
  129.  
  130. The action depends upon the message received. If the actual length of the
  131. message text is zero AND shutdown is enabled, the Macintosh will be shutdown
  132. upon completion of Repsonse, otherwise messages of length zero are ignored.
  133. This feature is used in our Macintosh lab to shutdown all macintoshs at end
  134. of opening time.
  135.  
  136. If the message is not empty, a dialog will be put up at one of the next calls
  137. to SystemTask. The delay between two calls of the driver control routine by 
  138. SystemTask has been set to 30 ticks (half a second) to minimize overhead.
  139.  
  140. Note that if more than one message arrives within a short peroid of time, 
  141. only the last one will be saved.
  142.  
  143.  
  144. Interface Declaration
  145. =====================
  146.  
  147.  
  148. { Copyright 1988 Joachim Lindenberg, University of Karlsruhe, 
  149.                  Federal Republic of Germany. All rights reserved. }
  150.                  
  151. { Interface declarations for the Macintosh version. March 27th, 1988}
  152.  
  153. { Declaration of the globals used by driver/chooser device. The device control 
  154.   entry in the unittable contains in the storage field a handle to the NetRecs 
  155.   record. The  master pointer is actually located in the driver code segment 
  156.   because it must be accessed at interrupt time. Note that you might use 
  157.   BroadCast as notification manager by storing a message in the record and
  158.   setting the correct flags. Note however that any incoming message will
  159.   superseede your message. Note also, that messages arrive at interrupt time. }
  160.  
  161. const 
  162.  
  163.     ResId     = -4096;
  164.  
  165.     Release   = '05b3';    { current release }
  166.     Prefix    = '-';       { standard -      }
  167.     Delimiter = 'Q';       { option - $D1    }
  168.       
  169. type    
  170.  
  171.     Icon = array [0..31] of longint; IconPtr = ^Icon; IconHandle = ^IconPtr;
  172.  
  173.     ByteArray = packed array [0..1] of Byte; BytePtr = ^ByteArray; 
  174.     CharArray = packed array [0..1] of Char; CharPtr = ^CharArray;
  175.     ByteHandle = ^BytePtr; CharHandle = ^CharPtr;
  176.     IntPtr = ^Integer; IntHandle = ^IntPtr;
  177.  
  178.     MessageRec = record mText : str255; mIcon : Icon; end;
  179.     
  180.     NetRecs = record
  181.         version : OSType;          { used to check version of chooser against
  182.                                      the version of the driver. this is inited
  183.                                      to release during initialization. }
  184.         messageenabled,            { messages turned on, see note below }
  185.         shutdownenabled,           { does an empty message cause shutdown ? }
  186.         domessage,                 { a message has arrived }
  187.         includesicon : boolean;    { did it include an icon ? }
  188.         
  189.         nbpType : str32;           { NBP type, 'BroadCast', prefixed by Prefix
  190.                                      if disabled. NOTE: you must change both
  191.                                      messageenabled and nbpType during enable/
  192.                                      disable operations. }
  193.  
  194. { all of the following fields are used by the driver only }
  195.  
  196.         nbpNTE : NamesTableEntry;                            
  197.         request, response : ATPParamBlock; bds : BdsElement;
  198.         Time : longint; Socket : integer;
  199.         
  200.         message : MessageRec;      { the last message received }
  201.         
  202. { note : the following handles are obtained from resources on startup. all
  203.   of them are detached because the resource file is closed after that }
  204.    
  205.         broadcastdlog : Handle;    { the dialog definition ... }
  206.         broadcastditl : Handle;    { ... and its item list }
  207.         broadcasticon : Handle;    { the default icon }
  208.     end;
  209.  
  210.     NetPtr = ^NetRecs; NetHandle = ^NetPtr;
  211.  
  212. { end of Declaration }
  213. 226 Transfer completed. 8426 (8) bytes transferred.
  214. 8426 bytes received in 67.53 seconds (0.12 Kbytes/s)
  215. ftp>